Reading Heartbeat Series Samples#

The Scripting app provides access to heartbeat series samples stored in Apple Health using the global API Health.queryHeartbeatSeriesSamples(). These samples represent beat-to-beat heartbeat intervals collected during workouts or background monitoring sessions (usually via Apple Watch).

Each record contains the time range, number of beats, and optional metadata, but not the raw interval values.

What Is a Heartbeat Series Sample?#

A HealthHeartbeatSeriesSample object includes:

• uuid: A unique identifier for the sample
• sampleType: Always "heartbeatSeries"
• startDate / endDate: The time range over which the heartbeats were recorded
• count: The number of heartbeat intervals collected
• metadata: Optional information attached by the recording source (e.g., watch model, app version)

Note: This API provides high-level information about the series. It does not expose individual heartbeat intervals.

API Reference#

1Health.queryHeartbeatSeriesSamples(
2  options?: {
3    startDate?: Date
4    endDate?: Date
5    limit?: number
6    strictStartDate?: boolean
7    strictEndDate?: boolean
8    sortDescriptors?: Array<{
9      key: "startDate" | "endDate"
10      order?: "forward" | "reverse"
11    }>
12    requestPermissions?: HealthQuantityType[]
13  }
14): Promise<HealthHeartbeatSeriesSample[]>

Parameters#

Example: Query Recent Heartbeat Series#

1const results = await Health.queryHeartbeatSeriesSamples({
2  startDate: new Date("2025-07-01T00:00:00"),
3  endDate: new Date("2025-07-05T00:00:00"),
4  limit: 10,
5  sortDescriptors: [{ key: "startDate", order: "reverse" }]
6})
7
8for (const sample of results) {
9  console.log("UUID:", sample.uuid)
10  console.log("Start:", sample.startDate)
11  console.log("End:", sample.endDate)
12  console.log("Heartbeat count:", sample.count)
13  console.log("Metadata:", sample.metadata)
14  console.log("---")
15}

Limitations#

• Individual heartbeat intervals (R–R data) are not accessible via this API.

• To analyze HRV or derive BPM, you’ll need only the count and duration:

  1const durationSeconds = (sample.endDate.getTime() - sample.startDate.getTime()) / 1000
  2const avgBPM = (sample.count / durationSeconds) * 60

• Gaps or anomalies (e.g. pauses, data loss) are not available in this summary sample.

Summary#

To read heartbeat series:

1. Call Health.queryHeartbeatSeriesSamples() with optional date range or limits.
2. Iterate through the returned HealthHeartbeatSeriesSample objects.
3. Each item provides startDate, endDate, count, and metadata.
4. You can approximate average BPM over the session using count and duration.

This API is useful for overviewing heart rhythm tracking sessions, especially for detecting how often heart rate was sampled during a day or workout.